<!DOCTYPE html>
<html>
<head>
<title>How to build the MuPDF viewer for Android</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>

<body>

<header>
<h1>How to build the MuPDF viewer for Android</h1>
</header>

<nav>
<a href="http://mupdf.com/index.html">ABOUT</a>
<a href="http://mupdf.com/news.html">NEWS</a>
<a href="index.html">DOCUMENTATION</a>
<a href="http://mupdf.com/downloads/">DOWNLOAD</a>
<a href="http://git.ghostscript.com/?p=mupdf.git;a=summary">SOURCE</a>
<a href="https://bugs.ghostscript.com/">BUGS</a>
</nav>

<article>

<h2>Prerequisites</h2>

<p>
You need a working Android development environment, consisting of the Android
SDK and the Android NDK. The easiest way is to use Android Studio to download
and install the SDK and NDK. Make sure that the Android/Sdk/tools and
Android/Sdk/ndk-bundle directories are on your path.

<p>
You also need Oracle's Java JDK (OpenJDK is not compatible with Android).
You also need the Apache Ant build system.
You also need Git, GNU Make, and a C compiler.

<p>
If everything is working, you should be able to run these commands
from the command line:

<blockquote>
	Android SDK tools: android, emulator, adb and apksigner.<br>
	Android NDK tools: ndk-build.<br>
	Oracle Java JDK 8: java, javac and keytool.<br>
	Git: git.<br>
	GNU Make: make, or gmake.<br>
	C compiler: cc, gcc, or clang.
</blockquote>

<h2>Building</h2>

<p>
Download the project using Git (and don't forget the --recursive flag):

<pre>
$ git clone --recursive git://git.ghostscript.com/mupdf-android-viewer-mini.git
</pre>

<p>
If all tools have been installed as per the prerequisites, first use your
host compiler to run the 'generate' step in the mupdf project:

<pre>
$ make -C libmupdf generate
</pre>

<p>The build the app using the gradle wrapper:

<pre>
$ ./gradlew assembleDebug
</pre>

<p>
You may need to set ANDROID_HOME or add a local.properties configuration
file to point to where you have installed the Android SDK.

<h2>Running</h2>

<p>
To run the app in the android emulator, first you'll need to set up an
"Android Virtual Device" for the emulator. Run "android avd" and create
a new device. You can also use Android Studio to set up a virtual device.
Use the x86 ABI for best emulator performance.

<p>
Then launch the emulator, or connect a device with USB debugging enabled:

<pre>
$ emulator -avd MyVirtualDevice &
</pre>

<p>
Then copy some test files to the device:

<pre>
$ adb push file.pdf /mnt/sdcard/Download
</pre>

<p>
Then install the app on the device:

<pre>
$ ./gradlew installDebug
</pre>

<p>
To see the error and debugging message log:

<pre>
$ adb logcat
</pre>

<h2>Release</h2>

<p>
To release you <b>MUST</b> first change the package name.
Do <b>NOT</b> use the com.artifex domain for your custom app!

<p>
Change all references to com.artifex.mupdf.mini into
com.YourCompanyName.mupdf.mini in the Java source files and XML resources.

<pre>
$ git mv src/com/artifex src/com/YourCompanyName
$ sed -i -e s,artifex,YourCompanyName,g AndroidManifest.xml
$ sed -i -e "s,package com.artifex,package com.YourCompanyName,g" src/com/YourCompanyName/mupdf/mini/*.java
$ sed -i -e s,artifex,YourCompanyName,g res/layout/*.xml
</pre>

<p>
In order to sign a release build, you will need to create a key and a key store.

<pre>
$ keytool -genkey -v -keystore android.keystore -alias MyKey -validity 3650 -keysize 2048 -keyalg RSA
</pre>

<p>
Then add the following entries to gradle.properties:

<pre>
RELEASE_KEY_STORE=android.keystore
RELEASE_KEY_STORE_PASSWORD=<i>your keystore password</i>
RELEASE_KEY_ALIAS=MyKey
RELEASE_KEY_ALIAS_PASSWORD=<i>your key password</i>
</pre>

<p>
If your keystore has been set up properly, you can now build a release APK.

<pre>
$ ./gradlew assembleRelease
</pre>

<p>
First verify that the release APK has indeed been signed by the correct key.

<pre>
apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-debug.apk
apksigner verify --print-certs ./build/outputs/apk/mupdf-x86-release.apk
</pre>

<p>
The debug APK should be signed by <i>Android Debug</i> while the release APK
ought to be signed with the key you created above.

<p>
Finally install the release app on the device:

<pre>
$ ./gradlew installRelease
</pre>

<p>
Good Luck!

</article>

<footer>
<a href="http://artifex.com"><img src="artifex-logo.png" align="right"></a>
Copyright &copy; 2006-2017 Artifex Software Inc.
</footer>

</body>
</html>
